Skip to content

crypto: support loading private keys through STORE loaders - #63949

Open
panva wants to merge 4 commits into
nodejs:mainfrom
panva:keyobject-stores
Open

crypto: support loading private keys through STORE loaders#63949
panva wants to merge 4 commits into
nodejs:mainfrom
panva:keyobject-stores

Conversation

@panva

@panva panva commented Jun 16, 2026 •
edited
Loading

Copy link
Copy Markdown
Member

Allow crypto.createPrivateKey() and APIs that consume private keys, such as crypto.sign(), crypto.privateDecrypt(), crypto.diffieHellman(), and crypto.decapsulate(), to load private keys through configured OpenSSL STORE loaders using WHATWG URL objects.

This supports direct URL input:

import { createPrivateKey } from 'node:crypto';

const key = createPrivateKey(
  new URL('file:///path/to/private-key.pem'),
);

It also supports object input with an optional passphrase or PIN and OpenSSL property query:

import { createPrivateKey, sign } from 'node:crypto';

const key = createPrivateKey({
  key: new URL('pkcs11:token=node;object=signing-key;type=private'),
  passphrase: process.env.PKCS11_PIN,
  properties: 'provider=pkcs11',
});

const signature = sign('sha256', Buffer.from('payload'), key);

The provider implementing the STORE loader must already be loaded in Node.js' default OpenSSL library context, for example through OpenSSL configuration. This API does not load providers.

passphrase is forwarded to the loader as its passphrase or PIN. properties is an OpenSSL property query used to select the STORE loader; it is not appended to the URL and is distinct from provider-specific URI parameters.

Why URL?

A URL distinguishes an external key reference from existing key material. Strings, buffers, typed arrays, and formatted objects retain their existing PEM, DER, JWK, and raw-key semantics. This avoids adding STORE loading to the key import/export format namespace.

URL input is accepted only in private-key contexts. A public key can be derived by first loading the private key and passing the resulting KeyObject to crypto.createPublicKey().

The resulting provider-backed key is an ordinary KeyObject and interoperates with existing private-key operations, key metadata, public-key derivation, and toCryptoKey() where supported by the key algorithm and provider. Provider policy continues to control permitted operations and private-key exportability.

The native STORE-loading path is available with OpenSSL >= 3.

Permission model

STORE loading adds the global openssl.store permission, enabled with --allow-openssl-store and exposed through the runtime permission APIs:

process.permission.has('openssl.store'); // true
process.permission.drop('openssl.store');
process.permission.has('openssl.store'); // false

This permission grants broad authority to configured STORE loaders. Loaders may access files, devices, tokens, or the network, and that access is not constrained by the fs.read, fs.write, or net permission scopes.

This broad capability matches OpenSSL's behavior: STORE loaders perform their own I/O, and OpenSSL may try its file loader before another loader for opaque URIs.

When STORE access is denied, Node.js redacts the URI from the permission error resource and permission diagnostics.

Passphrases and errors

Credentials should be supplied through passphrase rather than embedded in the URI.

If OpenSSL requests a passphrase and none was provided, Node.js throws ERR_MISSING_PASSPHRASE, matching existing encrypted private-key import behavior. Incorrect passphrases and provider failures continue to surface as OpenSSL errors.

Node.js redacts URIs from its own permission-denial errors. Errors reported by OpenSSL or a provider after loading begins may still include the URI.

@panva panva added the wip Issues and PRs that are still a work in progress. label Jun 16, 2026
@nodejs-github-bot

nodejs-github-bot commented Jun 16, 2026

Copy link
Copy Markdown
Collaborator

Review requested:

  • @nodejs/actions
  • @nodejs/config
  • @nodejs/crypto
  • @nodejs/gyp
  • @nodejs/security-wg

@nodejs-github-bot nodejs-github-bot added lib / src Issues and PRs related to general changes in the lib or src directory. needs-ci PRs that need a full CI run. labels Jun 16, 2026
@panva
panva requested a review from tniessen June 17, 2026 09:04
@panva
panva force-pushed the keyobject-stores branch 2 times, most recently from 43f0d74 to 96c5081 Compare June 18, 2026 08:52
@panva panva removed the wip Issues and PRs that are still a work in progress. label Jun 18, 2026
@panva
panva force-pushed the keyobject-stores branch 2 times, most recently from ddd7eaf to 35bb771 Compare June 18, 2026 09:03
jasnell
jasnell previously approved these changes Jun 19, 2026
View reviewed changes
@panva
panva force-pushed the keyobject-stores branch from 35bb771 to 9d23b6b Compare June 29, 2026 13:01
@panva
panva dismissed jasnell’s stale review June 29, 2026 13:02

I changed the feature shape quite a bit. Dismissing a stale review.

@panva
panva force-pushed the keyobject-stores branch from f32c6b7 to dffa62d Compare June 29, 2026 16:13
@panva
panva force-pushed the keyobject-stores branch from 6f3d2cb to e496577 Compare July 8, 2026 22:27
@jasnell jasnell added the semver-minor PRs that contain new features and should be released in the next minor version. label Jul 8, 2026
@panva

This comment was marked as resolved.

Sign in to view
@panva panva added the wip Issues and PRs that are still a work in progress. label Jul 8, 2026
@codecov

codecov Bot commented Jul 9, 2026 •
edited
Loading

Copy link
Copy Markdown

Codecov Report

❌ Patch coverage is 74.06143% with 76 lines in your changes missing coverage. Please review.
✅ Project coverage is 90.28%. Comparing base (a46087d) to head (7725852).
⚠️ Report is 1 commits behind head on main.

Files with missing lines Patch % Lines
src/crypto/crypto_keys.cc 56.97% 21 Missing and 16 partials ⚠️
src/crypto/crypto_sig.cc 58.44% 12 Missing and 20 partials ⚠️
lib/internal/crypto/keys.js 95.60% 4 Missing ⚠️
src/crypto/crypto_ec.cc 33.33% 0 Missing and 2 partials ⚠️
src/permission/openssl_store_permission.cc 87.50% 0 Missing and 1 partial ⚠️
Additional details and impacted files 
@@            Coverage Diff             @@
##             main   #63949      +/-   ##
==========================================
- Coverage   90.29%   90.28%   -0.02%     
==========================================
  Files         760      762       +2     
  Lines      247061   247317     +256     
  Branches    46584    46634      +50     
==========================================
+ Hits       223096   223286     +190     
- Misses      15437    15479      +42     
- Partials     8528     8552      +24
Files with missing lines Coverage Δ
lib/internal/process/permission.js 81.70% <100.00%> (+0.22%) ⬆️
lib/internal/process/pre_execution.js 97.84% <100.00%> (-0.12%) ⬇️
lib/internal/url.js 93.23% <100.00%> (+0.05%) ⬆️
src/crypto/crypto_cipher.cc 76.73% <100.00%> (+0.04%) ⬆️
src/crypto/crypto_keys.h 62.22% <ø> (ø)
src/env.cc 85.65% <100.00%> (+0.35%) ⬆️
src/node_options.cc 76.74% <100.00%> (+0.02%) ⬆️
src/node_options.h 98.02% <100.00%> (+<0.01%) ⬆️
src/permission/openssl_store_permission.h 100.00% <100.00%> (ø)
src/permission/permission.cc 82.56% <100.00%> (+0.24%) ⬆️
... and 6 more

... and 25 files with indirect coverage changes

🚀 New features to boost your workflow:
  • ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
  • 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

@panva panva added review wanted PRs that need reviews. and removed wip Issues and PRs that are still a work in progress. labels Jul 9, 2026
@nodejs-github-bot

This comment was marked as outdated.

Sign in to view
@panva panva added the experimental Issues and PRs related to experimental features. label Jul 9, 2026
@panva panva mentioned this pull request Jul 9, 2026
Closed
@nodejs-github-bot

This comment was marked as outdated.

Sign in to view
@panva

This comment was marked as resolved.

Sign in to view
@panva
panva force-pushed the keyobject-stores branch from b1d5d84 to 70d8d79 Compare July 10, 2026 19:43
@panva panva changed the title crypto: support OpenSSL STORE private keys crypto: support loading private keys through STORE loaders Jul 10, 2026
@diegomarino diegomarino mentioned this pull request Jul 10, 2026
Merged
3 tasks
@nodejs-github-bot

This comment was marked as outdated.

Sign in to view
@nodejs-github-bot

This comment was marked as outdated.

Sign in to view
@nodejs-github-bot

This comment was marked as outdated.

Sign in to view
aduh95
aduh95 reviewed Jul 27, 2026
View reviewed changes
Comment thread test/parallel/test-crypto-key-store-pkcs11.js Outdated
aduh95
aduh95 reviewed Jul 27, 2026
View reviewed changes
Comment thread shell.nix Outdated
aduh95
aduh95 reviewed Jul 27, 2026
View reviewed changes
Comment thread tools/nix/pkcs11.nix Outdated
aduh95
aduh95 reviewed Jul 27, 2026
View reviewed changes
Comment thread tools/nix/pkcs11.nix Outdated
aduh95
aduh95 reviewed Jul 27, 2026
View reviewed changes
Comment thread tools/nix/pkcs11.nix Outdated
@panva
panva force-pushed the keyobject-stores branch from a30ead7 to 5ca4525 Compare July 27, 2026 22:37
@nodejs-github-bot

This comment was marked as outdated.

Sign in to view
aduh95
aduh95 reviewed Jul 28, 2026
View reviewed changes
Comment thread tools/nix/pkcs11.nix Outdated
aduh95
aduh95 reviewed Jul 28, 2026
View reviewed changes
Comment thread shell.nix Outdated
aduh95
aduh95 reviewed Jul 28, 2026
View reviewed changes
Comment thread shell.nix Outdated
@aduh95

This comment was marked as resolved.

Sign in to view
@panva
panva force-pushed the keyobject-stores branch from 2bfdda7 to 4298a1d Compare July 28, 2026 18:22
@github-actions

github-actions Bot commented Jul 30, 2026

Copy link
Copy Markdown
Contributor
Platform Number of requisites Proportion of new derivations
x86_64-linux 450 -> 454 => +4 4 / 454 = 0.8%
aarch64-linux 451 -> 455 => +4 4 / 455 = 0.8%
x86_64-darwin 384 -> 390 => +6 6 / 390 = 1.5%
aarch64-darwin 390 -> 396 => +6 6 / 396 = 1.5%
Total 1675 -> 1695 => +20 20 / 1695 = 1.1%
Changelog 
@@ -688,0 +689 @@
+/nix/store/qh8zlpfxnwrib9a549i1g7rhydn64510-libtasn1-4.21.0 (aarch64-darwin)
@@ -689,0 +691 @@
+/nix/store/xc8mgyg7afwgxkk63zspriizhh63frfr-libtasn1-4.21.0 (x86_64-darwin)
@@ -990,0 +993,4 @@
+/nix/store/r6iib8l02032bh1bh06sd34sh42q9d3h-node-pkcs11-softhsm (aarch64-darwin)
+/nix/store/kywy4qkq8xd3w3h3628i39x7cwlci229-node-pkcs11-softhsm (aarch64-linux)
+/nix/store/sc2gzl4cd4dyjyqw7hhk7z5bgcxv4lah-node-pkcs11-softhsm (x86_64-darwin)
+/nix/store/zrqjcrqjinnmqx8lngjpkrxy5f07h9xw-node-pkcs11-softhsm (x86_64-linux)
@@ -1149,0 +1156,5 @@
+/nix/store/s812sqfl0rvksypb4v0b37xpf214anyr-openssl-pkcs11.cnf (aarch64-darwin)
+/nix/store/z1vaf4krscysh8scdff9x2m9338g77ng-openssl-pkcs11.cnf (aarch64-linux)
+/nix/store/l6cdd0qpa02yrr9wbja8zjyxlm7711ss-openssl-pkcs11.cnf (x86_64-darwin)
+/nix/store/a7v4gj95mfrf8zbqcclg4d25axyib3m0-openssl-pkcs11.cnf (x86_64-linux)
+/nix/store/988jzin1q70hrqd1bgljryqgh3b67s4i-p11-kit-0.26.2 (aarch64-darwin)
@@ -1150,0 +1162 @@
+/nix/store/8sl4a8wad1b8lmc9ddnxbmh1x35a4dpl-p11-kit-0.26.2 (x86_64-darwin)
@@ -1338,0 +1351,4 @@
+/nix/store/17x34zhqssjfhjfza071xrp8000sgq7f-pkcs11-provider-1.2.0 (aarch64-darwin)
+/nix/store/cyklk079xsziqjhbf5329sw42w3c34lw-pkcs11-provider-1.2.0 (aarch64-linux)
+/nix/store/scy6w598p9s9cgysh9knlbmkrh3vfxdq-pkcs11-provider-1.2.0 (x86_64-darwin)
+/nix/store/hs4qkb0wkhlvzypi3hbwgmjzh9wq1zaf-pkcs11-provider-1.2.0 (x86_64-linux)
@@ -1512,0 +1529,4 @@
+/nix/store/03ni5f24xkxbzkd92wzv6wzyarky3frk-softhsm-2.7.0 (aarch64-darwin)
+/nix/store/wy7a65hjjf83v20nmqx86cqvfjgcx31x-softhsm-2.7.0 (aarch64-linux)
+/nix/store/39vmyzrbc5l3hzz9bj5kz3ji9g31024k-softhsm-2.7.0 (x86_64-darwin)
+/nix/store/9r8fsp6vvgjv7mkhcq32lip1jm542bnf-softhsm-2.7.0 (x86_64-linux)

@nodejs-github-bot

This comment was marked as outdated.

Sign in to view
@nodejs-github-bot

This comment was marked as outdated.

Sign in to view
@nodejs-github-bot

This comment was marked as outdated.

Sign in to view
@nodejs-github-bot

This comment was marked as outdated.

Sign in to view
@panva

panva commented Aug 1, 2026 •
edited
Loading

Copy link
Copy Markdown
Member Author

CI shows a genuine windows clang test expectation mismatch

panva added 3 commits August 1, 2026 14:48
@panva
crypto: support loading private keys through STORE loaders
9a37bf8 
Accept WHATWG URL objects in private-key inputs and load referenced keys
through OpenSSL STORE loaders. Pass optional property queries and
passphrases while preserving provider-owned EVP_PKEY objects for
ordinary KeyObject and CryptoKey operations.

Signed-off-by: Filip Skokan <panva.ip@gmail.com>
@panva
fixup! crypto: support loading private keys through STORE loaders
5202c20
@panva
fixup! crypto: support loading private keys through STORE loaders
7ebfca9
@panva
panva force-pushed the keyobject-stores branch from 20df85e to 7ebfca9 Compare August 1, 2026 12:49
@nodejs-github-bot

This comment was marked as outdated.

Sign in to view
@github-actions

github-actions Bot commented Aug 1, 2026

Copy link
Copy Markdown
Contributor
Platform Number of requisites Proportion of new derivations
x86_64-linux 450 -> 454 => +4 4 / 454 = 0.8%
aarch64-linux 451 -> 455 => +4 4 / 455 = 0.8%
x86_64-darwin 384 -> 390 => +6 6 / 390 = 1.5%
aarch64-darwin 390 -> 396 => +6 6 / 396 = 1.5%
Total 1675 -> 1695 => +20 20 / 1695 = 1.1%
Changelog 
@@ -688,0 +689 @@
+/nix/store/qh8zlpfxnwrib9a549i1g7rhydn64510-libtasn1-4.21.0 (aarch64-darwin)
@@ -689,0 +691 @@
+/nix/store/xc8mgyg7afwgxkk63zspriizhh63frfr-libtasn1-4.21.0 (x86_64-darwin)
@@ -990,0 +993,4 @@
+/nix/store/r6iib8l02032bh1bh06sd34sh42q9d3h-node-pkcs11-softhsm (aarch64-darwin)
+/nix/store/kywy4qkq8xd3w3h3628i39x7cwlci229-node-pkcs11-softhsm (aarch64-linux)
+/nix/store/sc2gzl4cd4dyjyqw7hhk7z5bgcxv4lah-node-pkcs11-softhsm (x86_64-darwin)
+/nix/store/zrqjcrqjinnmqx8lngjpkrxy5f07h9xw-node-pkcs11-softhsm (x86_64-linux)
@@ -1149,0 +1156,5 @@
+/nix/store/s812sqfl0rvksypb4v0b37xpf214anyr-openssl-pkcs11.cnf (aarch64-darwin)
+/nix/store/z1vaf4krscysh8scdff9x2m9338g77ng-openssl-pkcs11.cnf (aarch64-linux)
+/nix/store/l6cdd0qpa02yrr9wbja8zjyxlm7711ss-openssl-pkcs11.cnf (x86_64-darwin)
+/nix/store/a7v4gj95mfrf8zbqcclg4d25axyib3m0-openssl-pkcs11.cnf (x86_64-linux)
+/nix/store/988jzin1q70hrqd1bgljryqgh3b67s4i-p11-kit-0.26.2 (aarch64-darwin)
@@ -1150,0 +1162 @@
+/nix/store/8sl4a8wad1b8lmc9ddnxbmh1x35a4dpl-p11-kit-0.26.2 (x86_64-darwin)
@@ -1338,0 +1351,4 @@
+/nix/store/17x34zhqssjfhjfza071xrp8000sgq7f-pkcs11-provider-1.2.0 (aarch64-darwin)
+/nix/store/cyklk079xsziqjhbf5329sw42w3c34lw-pkcs11-provider-1.2.0 (aarch64-linux)
+/nix/store/scy6w598p9s9cgysh9knlbmkrh3vfxdq-pkcs11-provider-1.2.0 (x86_64-darwin)
+/nix/store/hs4qkb0wkhlvzypi3hbwgmjzh9wq1zaf-pkcs11-provider-1.2.0 (x86_64-linux)
@@ -1512,0 +1529,4 @@
+/nix/store/03ni5f24xkxbzkd92wzv6wzyarky3frk-softhsm-2.7.0 (aarch64-darwin)
+/nix/store/wy7a65hjjf83v20nmqx86cqvfjgcx31x-softhsm-2.7.0 (aarch64-linux)
+/nix/store/39vmyzrbc5l3hzz9bj5kz3ji9g31024k-softhsm-2.7.0 (x86_64-darwin)
+/nix/store/9r8fsp6vvgjv7mkhcq32lip1jm542bnf-softhsm-2.7.0 (x86_64-linux)

@github-actions

github-actions Bot commented Aug 1, 2026

Copy link
Copy Markdown
Contributor
Platform Number of requisites Proportion of new derivations
x86_64-linux 450 -> 454 => +4 4 / 454 = 0.8%
aarch64-linux 451 -> 455 => +4 4 / 455 = 0.8%
x86_64-darwin 384 -> 390 => +6 6 / 390 = 1.5%
aarch64-darwin 390 -> 396 => +6 6 / 396 = 1.5%
Total 1675 -> 1695 => +20 20 / 1695 = 1.1%
Changelog 
@@ -688,0 +689 @@
+/nix/store/qh8zlpfxnwrib9a549i1g7rhydn64510-libtasn1-4.21.0 (aarch64-darwin)
@@ -689,0 +691 @@
+/nix/store/xc8mgyg7afwgxkk63zspriizhh63frfr-libtasn1-4.21.0 (x86_64-darwin)
@@ -990,0 +993,4 @@
+/nix/store/r6iib8l02032bh1bh06sd34sh42q9d3h-node-pkcs11-softhsm (aarch64-darwin)
+/nix/store/kywy4qkq8xd3w3h3628i39x7cwlci229-node-pkcs11-softhsm (aarch64-linux)
+/nix/store/sc2gzl4cd4dyjyqw7hhk7z5bgcxv4lah-node-pkcs11-softhsm (x86_64-darwin)
+/nix/store/zrqjcrqjinnmqx8lngjpkrxy5f07h9xw-node-pkcs11-softhsm (x86_64-linux)
@@ -1149,0 +1156,5 @@
+/nix/store/s812sqfl0rvksypb4v0b37xpf214anyr-openssl-pkcs11.cnf (aarch64-darwin)
+/nix/store/z1vaf4krscysh8scdff9x2m9338g77ng-openssl-pkcs11.cnf (aarch64-linux)
+/nix/store/l6cdd0qpa02yrr9wbja8zjyxlm7711ss-openssl-pkcs11.cnf (x86_64-darwin)
+/nix/store/a7v4gj95mfrf8zbqcclg4d25axyib3m0-openssl-pkcs11.cnf (x86_64-linux)
+/nix/store/988jzin1q70hrqd1bgljryqgh3b67s4i-p11-kit-0.26.2 (aarch64-darwin)
@@ -1150,0 +1162 @@
+/nix/store/8sl4a8wad1b8lmc9ddnxbmh1x35a4dpl-p11-kit-0.26.2 (x86_64-darwin)
@@ -1338,0 +1351,4 @@
+/nix/store/17x34zhqssjfhjfza071xrp8000sgq7f-pkcs11-provider-1.2.0 (aarch64-darwin)
+/nix/store/cyklk079xsziqjhbf5329sw42w3c34lw-pkcs11-provider-1.2.0 (aarch64-linux)
+/nix/store/scy6w598p9s9cgysh9knlbmkrh3vfxdq-pkcs11-provider-1.2.0 (x86_64-darwin)
+/nix/store/hs4qkb0wkhlvzypi3hbwgmjzh9wq1zaf-pkcs11-provider-1.2.0 (x86_64-linux)
@@ -1512,0 +1529,4 @@
+/nix/store/03ni5f24xkxbzkd92wzv6wzyarky3frk-softhsm-2.7.0 (aarch64-darwin)
+/nix/store/wy7a65hjjf83v20nmqx86cqvfjgcx31x-softhsm-2.7.0 (aarch64-linux)
+/nix/store/39vmyzrbc5l3hzz9bj5kz3ji9g31024k-softhsm-2.7.0 (x86_64-darwin)
+/nix/store/9r8fsp6vvgjv7mkhcq32lip1jm542bnf-softhsm-2.7.0 (x86_64-linux)

@mcollina

mcollina commented Aug 1, 2026

Copy link
Copy Markdown
Member

This is an AI-generated review looking for security vulnerabilities at the request of @panva.

I found one issue that should be resolved before landing and two additional hardening issues:

  1. Opaque STORE URIs can be satisfied by a local file. test/parallel/test-permission-openssl-store.js:83-92 confirms that pkcs11:priv.pem loads a local file with that name before consulting the PKCS#11 loader. An attacker able to write in the process working directory could substitute a software key for an expected HSM-backed key. Please prevent the file loader from satisfying non-file: URLs, or otherwise require/pin the intended loader. At minimum, this key-substitution risk needs prominent user-facing documentation.

  2. Mutable URL accessors can redirect the load. lib/internal/crypto/keys.js:545-548 reads public href and protocol accessors after the private-field brand check in lib/internal/url.js:822. Redefining URL.prototype.href, or passing a branded URL subclass with an overridden getter, redirects a previously created trusted URL to another STORE URI. Please obtain the canonical URL through an internal private-slot helper rather than mutable public accessors, and add regression coverage.

  3. STORE close errors can remain queued after a successful load. At deps/ncrypto/ncrypto.cc:3766-3768, ERR_clear_error() runs before StoreCtxPointer destruction. OSSL_STORE_close() can subsequently push provider errors, which can contaminate later crypto failures on paths without an outer error guard, including DH/KEM configuration. Please close/reset ctx before clearing the OpenSSL error queue and add coverage for a close callback that raises an error.

I did not find a permission bypass, memory-safety issue, use-after-free, or provider-lifetime bug. The focused STORE, permission, and sign/verify tests passed, as did the reported CI matrix.

Requesting changes for the issues above before this lands.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

@aduh95 aduh95 aduh95 left review comments
@tniessen tniessen Awaiting requested review from tniessen
@jasnell jasnell Awaiting requested review from jasnell

At least 1 approving review is required to merge this pull request.

Assignees

No one assigned

Labels

experimental Issues and PRs related to experimental features. lib / src Issues and PRs related to general changes in the lib or src directory. needs-ci PRs that need a full CI run. review wanted PRs that need reviews. semver-minor PRs that contain new features and should be released in the next minor version.

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

5 participants

@panva @nodejs-github-bot @aduh95 @mcollina @jasnell